home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / dmedia / dmLTC.z / dmLTC
Encoding:
Text File  |  2002-10-03  |  11.9 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ddddmmmmLLLLTTTTCCCC((((3333ddddmmmm))))                                                          ddddmmmmLLLLTTTTCCCC((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrCCCCrrrreeeeaaaatttteeee, ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrSSSSeeeettttPPPPaaaarrrraaaammmmssss, ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeee,
  10.      ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrDDDDeeeessssttttrrrrooooyyyy - decode linear timecode (LTC)
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ddddmmmm____llllttttcccc....hhhh>>>>
  14.  
  15.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrCCCCrrrreeeeaaaatttteeee
  16.            (((( DDDDMMMMLLLLTTTTCCCCddddeeeeccccooooddddeeeerrrr ********ddddeeeeccccooooddddeeeerrrr,,,, iiiinnnntttt ttttcccc____ttttyyyyppppeeee))));;;;
  17.  
  18.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrSSSSeeeettttPPPPaaaarrrraaaammmmssss
  19.            (((( DDDDMMMMLLLLTTTTCCCCCCCCoooonnnntttteeeexxxxtttt ****ddddeeeeccccooooddddeeeerrrr,,,,
  20.              DDDDMMMMppppaaaarrrraaaammmmssss ****aaaauuuuddddiiiiooooppppaaaarrrraaaammmmssss,,,,
  21.              iiiinnnntttt ttttiiiimmmmeeeeccccooooddddeeeeCCCChhhhaaaannnnnnnneeeellll))));;;;
  22.  
  23.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeee
  24.            (((( DDDDMMMMLLLLTTTTCCCCCCCCoooonnnntttteeeexxxxtttt ****ddddeeeeccccooooddddeeeerrrr,,,,
  25.              vvvvooooiiiidddd ********ssssaaaammmmpppplllleeeeBBBBuuuuffffffffeeeerrrr,,,,
  26.              iiiinnnntttt ****ssssaaaammmmpppplllleeeeCCCCoooouuuunnnntttt,,,,
  27.              DDDDMMMMLLLLTTTTCCCCccccooooddddeeee ****ddddmmmmLLLLTTTTCCCCccccooooddddeeeewwwwoooorrrrdddd))));;;;
  28.  
  29.      vvvvooooiiiidddd DDDDMMMMLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrDDDDeeeessssttttrrrrooooyyyy
  30.            (((( DDDDMMMMLLLLTTTTCCCCCCCCoooonnnntttteeeexxxxtttt ****ddddeeeeccccooooddddeeeerrrr ))));;;;
  31.  
  32. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  33.      These routines provide a mechanism for decoding linear (or longitudinal)
  34.      time code (LTC).  LTC is a mechanism for storing and transferring SMPTE
  35.      time code as an audio-like waveform.  Applications may use LTC to
  36.      synchronize audio, video, or other events with external devices by
  37.      decoding an LTC signal connected to an audio input port, or they may
  38.      parse the LTC code from a previously captured audio or movie file.
  39.  
  40.      To decode LTC from an external device, the LTC or time code output of the
  41.      device should be connected to an audio input channel on the workstation.
  42.      The application then opens an audio port using the audio library (see
  43.      AAAALLLLiiiinnnnttttrrrroooo(3dm)).
  44.  
  45.      In order to decode LTC, you first create a LTC decoder using
  46.      ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrCCCCrrrreeeeaaaatttteeee.  The _t_c__t_y_p_e parameter tells the decoder what format
  47.      and rate of timecode to expect.  The possible values for _t_c__t_y_p_e, defined
  48.      in <<<<ddddmmmmeeeeddddiiiiaaaa////ddddmmmm____ttttiiiimmmmeeeeccccooooddddeeee....hhhh>>>>, are explained in ttttcccc____ttttyyyyppppeeee(3dm).  The
  49.      ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrCCCCrrrreeeeaaaatttteeee routine only pays attention to the DM_TC_FORMAT and
  50.      DM_TC_RATE bits of the passed-in _t_c__t_y_p_e, since it will be able to
  51.      determine the drop-frame/non-drop-frame status from the LTC code itself.
  52.      The currently supported timecode formats are DDDDMMMM____TTTTCCCC____FFFFOOOORRRRMMMMAAAATTTT____NNNNTTTTSSSSCCCC,
  53.      DDDDMMMM____TTTTCCCC____FFFFOOOORRRRMMMMAAAATTTT____PPPPAAAALLLL, and DDDDMMMM____TTTTCCCC____FFFFOOOORRRRMMMMAAAATTTT____FFFFIIIILLLLMMMM.  The currently supported
  54.      timecode rate values are DDDDMMMM____TTTTCCCC____RRRRAAAATTTTEEEE____2222999999997777, DDDDMMMM____TTTTCCCC____RRRRAAAATTTTEEEE____33330000, DDDDMMMM____TTTTCCCC____RRRRAAAATTTTEEEE____22224444,
  55.      and DDDDMMMM____TTTTCCCC____RRRRAAAATTTTEEEE____22225555.
  56.  
  57.      The value returned by ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrCCCCrrrreeeeaaaatttteeee must be passed to all of the
  58.      other LTC routines.  It may be freed by calling DDDDMMMMLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrDDDDeeeessssttttrrrrooooyyyy.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ddddmmmmLLLLTTTTCCCC((((3333ddddmmmm))))                                                          ddddmmmmLLLLTTTTCCCC((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      The audio port configuration is set with ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeeerrrrSSSSeeeettttPPPPaaaarrrraaaammmmssss.  The
  75.      sample format, sample resolution, and number of channels is specified by
  76.      the _a_u_d_i_o_p_a_r_a_m_s parameter.  The channel that the LTC signal is to be
  77.      received on (0, 1, 2, or 3) is specified by the _t_i_m_e_c_o_d_e_C_h_a_n_n_e_l
  78.      parameter.
  79.  
  80.      After calling AAAALLLLrrrreeeeaaaaddddssssaaaammmmppppssss to read a buffer of audio (or otherwise
  81.      obtaining the LTC samples), the procedure ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeee should be called to
  82.      decode the LTC.  The _s_a_m_p_l_e_B_u_f_f_e_r is a pointer to pointer to a buffer
  83.      containing audio samples in the format specified by ddddmmmmLLLLTTTTCCCCSSSSeeeettttCCCCoooonnnnffffiiiigggg.  The
  84.      _s_a_m_p_l_e_C_o_u_n_t is a pointer to an integer containing the number of samples
  85.      contained in _s_a_m_p_l_e_B_u_f_f_e_r.  Upon return, ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeee advances the sample
  86.      buffer pointer pointed to by _s_a_m_p_l_e_B_u_f_f_e_r past where it has decoded and
  87.      decrements *_s_a_m_p_l_e_C_o_u_n_t by a like amount.  If an LTC word is successfully
  88.      decoded, dmLTCDecode returns DM_SUCCESS and fills _d_m_L_T_C_c_o_d_e_w_o_r_d with the
  89.      appropriate information.  An application should normally repeatedly call
  90.      ddddmmmmLLLLTTTTCCCCDDDDeeeeccccooooddddeeee until *_s_a_m_p_l_e_C_o_u_n_t reaches zero.
  91.  
  92.      The format of the LTC time code structure is as follows:
  93.  
  94.           typedef struct {
  95.                DMtimecode          tc;
  96.                unsigned int        dropFrame :1;
  97.                unsigned int        colorLock :1;
  98.                char                userType;
  99.                char                userData[4];
  100.           } DMLTCcode;
  101.  
  102.      The _t_c structure contains a SMPTE timecode structure.  This includes
  103.      hours, minutes, seconds, and frame count.  The _d_r_o_p_F_r_a_m_e flag indicates
  104.      whether or not the time code was recorded in a sequence that takes into
  105.      account the difference between the NTSC frame rate of 30000/1001 Hz and
  106.      the nominal rate of 30hz.  In drop frame mode, the SMPTE time code is
  107.      advanced by a count of three instead of one every minute, except for
  108.      minutes 0, 10, 20, 30, 40, and 50.  Note that this does not mean that an
  109.      actual video frame is ever dropped.  Note also that the timecode drop
  110.      frame scheme gives you a rate of exactly 29.97 timecode frames per second
  111.      over one day, but the video rate is 30000/1001, which does not equal
  112.      29.97.  So even when using drop frame timecode, timecode will drift away
  113.      from real time at a rate of approximately 2.5 frames per day.  See
  114.      ttttcccc____ttttyyyyppppeeee(3dm) for more information.
  115.  
  116.      The _c_o_l_o_r_L_o_c_k flag indicates the relationship between the timecode and
  117.      the underlying video signal's color subcarrier phase.  In the
  118.      DDDDMMMM____TTTTCCCC____FFFFOOOORRRRMMMMAAAATTTT____NNNNTTTTSSSSCCCC LTC, the flag is 1 if an even timecode address (that
  119.      is, a timecode whose "frame" value mod 2 is 1) identifies a "Color Frame
  120.      A" frame as described in ANSI/SMPTE 170M.  In the DDDDMMMM____TTTTCCCC____FFFFOOOORRRRMMMMAAAATTTT____PPPPAAAALLLL LTC,
  121.      the flag indicates that the 4-frame PAL color sequence is aligned with
  122.      the timecode sequence such that the first field of the day will be the
  123.      first field of "frame I" of the PAL color sequence as defined in ITU-R
  124.      BT. 470.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ddddmmmmLLLLTTTTCCCC((((3333ddddmmmm))))                                                          ddddmmmmLLLLTTTTCCCC((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      The _u_s_e_r_D_a_t_a field contains 32 additional bits used in some applications
  141.      to contain secondary time codes or other coded data.  In the LTC
  142.      codeword, the user bits are divided up into 8 4-bit user groups.
  143.      userData[0]&0x01 contains the (temporally) first bit of the first 4-bit
  144.      user group (this is bit 4 of the LTC codeword, using the bit numbering
  145.      scheme found in the LTC specifications), userData[0]&0x80 contains the
  146.      last bit of the second 4-bit user group, userData[1]&0x01 contains the
  147.      first bit of the third 4-bit user group, and so on.
  148.  
  149.      The _u_s_e_r_T_y_p_e field is currently undefined.
  150.  
  151. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  152.      ANSI/SMPTE 12M (defines LTC encoding for 525/60 video applications), EBU
  153.      Tech 3097 and IEC 461: 1986 (BS 6865:1987) (for 625/50 applications),
  154.      "Time Code: A User's Guide" by Ratcliff (Oxford: Focal Press),
  155.      dmTCFromSeconds(3dm), dmTCToSeconds(3dm), dmTCFromString(3dm),
  156.      dmTCFromString(3dm), dmTCFramesPerDay(3dm), dmTCFramesBetween(3dm),
  157.      dmVITC(3dm)
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.